#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
富途下单API参数分析
"""

from futu import *

def analyze_place_order_api():
    """分析place_order API的参数要求"""
    
    print("=== 富途下单API分析 ===")
    
    print("\n📋 API方法签名:")
    print("trd_ctx.place_order(price, qty, code, trd_side, order_type=OrderType.NORMAL, ...)")
    
    print("\n🔴 必需参数 (前4个):")
    print("  1. price    (float) - 订单价格")
    print("  2. qty      (float) - 订单数量")  
    print("  3. code     (str)   - 股票代码，如'US.AAPL'")
    print("  4. trd_side (enum)  - 买卖方向: TrdSide.BUY 或 TrdSide.SELL")
    
    print("\n🔵 重要可选参数:")
    print("  - order_type (enum) - 订单类型:")
    print("    * OrderType.NORMAL - 限价单(默认)")
    print("    * OrderType.MARKET - 市价单")
    print("  - trd_env (enum)    - 交易环境:")
    print("    * TrdEnv.SIMULATE - 模拟交易")
    print("    * TrdEnv.REAL     - 真实交易(默认)")

def user_requirement_analysis():
    """分析用户需求与API的匹配情况"""
    
    print("\n" + "="*50)
    print("=== 用户需求 vs API要求 ===")
    
    print("\n✅ 用户提供的参数:")
    print("  1. 买/卖方向    → 对应API的 trd_side ✅")
    print("  2. 股票代码     → 对应API的 code ✅") 
    print("  3. 交易金额     → ❌ API需要的是 price + qty")
    
    print("\n❌ 问题分析:")
    print("  • 用户想提供'交易金额'，但API需要'价格'和'数量'")
    print("  • 即使是市价单，也必须指定数量(qty)，不能直接指定金额")
    
    print("\n💡 解决方案:")
    print("  方案1: 使用市价单 + 预估数量")
    print("    - 用户提供交易金额 / 预估股价 = 数量")
    print("    - 设置 order_type=OrderType.MARKET, price=0")
    print("  ")
    print("  方案2: 快速获取股价 + 计算数量") 
    print("    - 先快速获取当前股价")
    print("    - 计算: 数量 = 交易金额 / 当前股价")
    print("    - 使用限价单或市价单")

def solution_examples():
    """提供解决方案的代码示例"""
    
    print("\n" + "="*50)
    print("=== 解决方案代码示例 ===")
    
    print("\n🔵 方案1: 纯市价单 (不查行情)")
    print("""
def place_order_by_amount_market(code, trd_side, amount, estimated_price=50):
    \"\"\"
    按交易金额下市价单
    code: 股票代码，如'US.AAPL'
    trd_side: TrdSide.BUY 或 TrdSide.SELL  
    amount: 交易金额，如1000美元
    estimated_price: 预估股价(用于计算大概数量)
    \"\"\"
    
    # 计算大概数量
    qty = int(amount / estimated_price)
    
    ret, data = trd_ctx.place_order(
        price=0.0,                    # 市价单价格为0
        qty=qty,                      # 根据金额估算的数量
        code=code,                    # 股票代码
        trd_side=trd_side,           # 买卖方向  
        order_type=OrderType.MARKET, # 市价单
        trd_env=TrdEnv.REAL         # 真实交易
    )
    return ret, data
""")

    print("\n🔵 方案2: 快速查价 + 精确下单")
    print("""
def place_order_by_amount_precise(code, trd_side, amount):
    \"\"\"
    先查价格，再按精确金额下单
    \"\"\"
    # 1. 快速获取股价
    quote_ctx = OpenQuoteContext(host='127.0.0.1', port=11111)
    ret, data = quote_ctx.get_market_snapshot(code)
    
    if ret != RET_OK:
        return ret, "获取股价失败"
        
    current_price = data['last_price'][0]
    
    # 2. 计算精确数量
    qty = int(amount / current_price)
    
    # 3. 下单
    ret, data = trd_ctx.place_order(
        price=current_price,          # 使用当前价格
        qty=qty,                      # 精确计算的数量
        code=code,
        trd_side=trd_side,
        order_type=OrderType.NORMAL,  # 限价单
        trd_env=TrdEnv.REAL
    )
    
    quote_ctx.close()
    return ret, data
""")

def recommendation():
    """给出推荐方案"""
    
    print("\n" + "="*50)
    print("=== 推荐方案 ===")
    
    print("\n🎯 推荐使用方案2 (快速查价)")
    print("原因:")
    print("  ✅ 精确控制交易金额")
    print("  ✅ 避免市价单的价格波动风险") 
    print("  ✅ 查价非常快，几乎没有延迟")
    print("  ✅ 可以在下单前显示预计花费")
    
    print("\n⚠️ 如果坚持不查行情:")
    print("  • 只能使用方案1，但需要预估股价")
    print("  • 实际交易金额可能与预期有差异")
    print("  • 建议至少提供股价范围估计")

if __name__ == "__main__":
    analyze_place_order_api()
    user_requirement_analysis() 
    solution_examples()
    recommendation()
